Inside Macintosh: QuickDraw GX Objects /

Chapter 8 - Tag Objects / Tag Objects Reference

Functions / Manipulating Tag Object Properties

GXSetTag

You can use the GXSetTag function to replace the tag type or contents of a tag object.

void GXSetTag(gxTag target, long tagType, long length, 
            const void *data);

target

A reference to the tag object whose contents you want to replace.

tagType

The new tag type to assign to the tag object referenced in the target parameter. If you pass 0 for this parameter, the tag type remains unchanged.

length

The length in bytes of the new data to place in the tag object. If you pass 0 for this parameter, the contents of the tag object remain unchanged and the data parameter is ignored.

data

A pointer to the new data to place in the tag object. If you pass nil for this parameter, the contents of the tag object (up to the length specified by length) remain unchanged.

DESCRIPTION

The GXSetTag function assigns the specified tag type and contents to the target tag object. You can set three of its parameters for different purposes:

• To change only the tag type and not the contents of a tag object, pass 0 in the length parameter, nil in the data parameter, and a nonzero value for tagType.
• To change only the contents and not the tag type, pass 0 in the tagType parameter, and valid values for length and data.
• To resize the tag object without changing its contents or type, pass the new size in the length parameter, nil in the data parameter, and 0 in the tagType parameter. If the new size of the contents is smaller than the previous size, the data is truncated to fit the new size. If the new size is greater than the previous size, the tag object is resized accordingly, but a new_tag_contains_invalid_data warning is posted.

Note that calling GXSetTag is different from using the GXGetTagStructure function to manipulate the contents of a tag object. Unlike GXGetTagStructure, GXSetTag allows you to change the size of the tag object.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
tag_is_nil
inconsistent_parameters	(debugging version)
tag_access_restricted	(debugging version)
Warnings
new_tag_contains_invalid_data

SEE ALSO

To retrieve the tag type and contents of a tag object, use the GXGetTag function, described in the previous section.

To directly manipulate the contents of a tag object in QuickDraw GX memory, rather than replacing its entire contents and tag type, use the GXGetTagStructure function, described on page 8-23.